Internet Info 1994 March

home *** CD-ROM | disk | FTP | other *** search

/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / networking / terms / kermit / b / ik0por.hlp < prev next >

Wrap

Text File | 1992-09-29 | 42.0 KB | 972 lines

IK0POR.HLP 1991 Sept Notes on porting Kermit-370 to other operating systems. This document consists of three parts: a general specification of functionality, a detailed guide to some of the more arcane sections of system-specific code in Kermit-370, and a summary of all the modules within Kermit-CMS. *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* A. Feasibility. The following is a list of system-specific operations that must (or should) be performed by Kermit-370. Each item is labeled with its degree of importance and with the name(s) of the macro and/or routine(s) that perform the function. The importance level is marked with ">>" and the program components with "<<". Names of macros are further marked with asterisks; routines are usually coupled with function codes. The presence of both a macro and a routine indicates that the macro serves only to invoke the routine. TERMINAL FUNCTIONS 1. Read from the terminal with possible prompt. Return length read. Leave text in specified buffer (unedited, if possible). Should follow techniques of utility programs, if any, such that command procedures can issue Kermit subcommands (if possible). >> Essential. << * RTEXT 2. Display text at the terminal. Ok if system supplies a CRLF. >> Essential. << * WTEXT 3. Test for stacked lines of terminal (or pseudo-terminal) input. >> Cosmetic. Avoids extra prompts and synchronizes "banner" display at startup. << SUPFNC,7 4. Set up a new prompt string, if necessary, for subsequent terminal read requests. >> Only if needed for #1. << SUPFNC,11 5. Clear the screen (if possible). >> Cosmetic. << SCRNIO,0 SYSTEM FUNCTIONS 6. Analyze user environment at startup and determine if suitable. Save any quantities needed and condition the line for entering commands. Determine, if possible, the terminal controller type insofar as that is necessary for establishing the method of file transfer. >> Essential. << SETMSG,1 7. Reperform system-dependent initialization after SET LINE command selects a new communication line. >> Needed for SET LINE subcommand. << SETMSG,5 + SCRNIO,3 8. Reverse any setup performed in #6 and clean up before returning to system. >> Essential. << SETMSG,4 9. Obtain free storage block of specified length. Return error code, if possible, when enough storage is not available. Method should be re-entrant if possible and must preserve registers 2-13 without recourse to the save area pointed to by R13. >> Essential. << * DMSFREE 10. Release free storage block of specified address and length. >> Essential. << * DMSFRET 11. Invoke the system HELP facility with optional operand string. >> Cosmetic, but very useful. << KHELP 12. Start typeout interception. If possible, this should include all possible terminal output regardless of source. At a minimum, it must result in messages from Kermit itself being saved in a buffer instead of displayed. The intercepted output may be stored wherever convenient. >> Needed for REMOTE operations in server mode. << SUPFNC,1 13. Stop interception and restore normal terminal functions. >> Needed for REMOTE operations in server mode. << SUPFNC,5 14. Retrieve intercepted messages and copy them, if necessary, to the Kermit disk buffer. >> Needed for REMOTE operations in server mode. << SUPFNC,2 15. Execute a host command (with or without interception). Generally, the command text may be of two different forms: either a text string extracted from a text buffer or a canonical, internal representation requiring perhaps less system overhead. Commands invoked by Kermit for purely internal purposes should be of the latter form. If possible, detect whether the command is legal before invoking it. Detect in any case whether the command is legal sooner or later. >> Cosmetic, but very useful. If necessary, a minimal set of host commands can be emulated. << SUPFNC,3 16. Retrieve original command string by which Kermit was invoked. This need not be done more than once (at startup). >> Needed for specifying a subcommand in original command line. << SUPFNC,6 17. Log off the current session. >> Needed for honoring BYE command. << SUPFNC,8 18. Wait for a specified time (in seconds). >> Needed for DELAY parameter and possibly for screen synchronizing. << SUPFNC,9 19. Return the current clock time (in centiseconds). The code is fully generic, even though the function is done in SUPFNC. >> Needed for statistics and long-packet optimizing. << SUPFNC,10 DISK/FILE-SYSTEM FUNCTIONS 20. Select a "working directory" specified by a string extracted from a text buffer. The directory is, of course, a concept defined within the context of the operating system. Subsequent files are preferentially read from and written to the directory. >> Needed if the directory concept is implemented: CWD subcommand. << CWDSET 21. Show space available in the "working directory" or other area. >> Needed for the SPACE subcommand. << DSPACE 22. Open a disk file by name for input (or return a non-zero code in case of failure). If necessary, refer to default file attributes specified to Kermit to aid in locating the file. Return a data area filled with the file attributes and a pointer to a storage block reserved for controlling the I/O (a "ticket"). OPENF is a generic macro. >> Essential. << * OPENF I + DISKIO,1 23. Open a disk file by name for output (or return a non-zero code in case of failure). If the file already exists, prepare to either overwrite it or append to it as the occasion requires. If the file is to be extended, be sure its attributes are not altered. Return a data area and "ticket" as with opening for input. >> Essential. << * OPENF O + DISKIO,2 24. Test for the existence of a file by name. Return a data area with the file attributes if found. >> Essential. << * OPENF T + DISKIO,3 25. Close the file specified by a "ticket". The ticket should then be "blank", so that reclosing would have no ill effects. CLOSF is generic. >> Essential. << * CLOSF + DISKIO,4 26. Write a record out to a disk file specified by a "ticket". The data address and length must be subject to change with each invocation, but must be retained if not explicitly changed. A completion code of 13 must be returned if the write encounters a full disk. Any other I/O error must return some other non-zero code. >> Essential. << * WRITF + DISKIO,10 27. Read a record in from a disk file specified by a "ticket". The buffer address and length must be subject to change with each invocation, but must be retained if not explicitly changed. If line numbers are kept in predictable locations within each record, there must be an option to remove them before returning the length of data read. If the end of the file is reached, a completion code of 12 must be returned. An error must return some other non-zero code. >> Essential. << * READF + DISKIO,9 or DISKIO,0 28. Update the disk directory for given file (specified by a "ticket") such that the file is still open for output. >> Needed for SET DEBUG SAVE subcommand. << * SAVEF + DISKIO,21 29. Set up disk directory search for files matching a given pattern name. This may entail as little as saving the pattern or as much as creating a file with the complete list of matches. Note: the former is dangerous in a multi-user system if the name space to be searched can be altered while Kermit is searching, especially if control blocks can be unchained. The latter approach also has a drawback, in that files can still be created or deleted after the "complete" list is made. NXTFSET is a generic macro. >> Needed for wildcard filespecs. << * NXTFSET + DISKIO,5 30. Fetch the next filespec from a directory search and get a pointer to a list of its file attributes. Must return a non-zero code if no more files (and must persist even if called repeatedly). NXTF is a generic macro. >> Needed for wildcard filespecs. << * NXTF + DISKIO,6 31. Clean up after a disk directory search. >> Needed for wildcard filespecs. << * NXTFSET END + DISKIO,7 32. Check candidate name of a directory for validity and accessibility. >> Needed for CWD subcommand. << * NXTFSET CWD + DISKIO,8 33. Test current directory (or environment) for sufficient disk space. >> Cosmetic, used for processing A-packets. << DISKIO,11 34. Analyze disk I/O error; set up error message and code. ERRF is a generic macro. >> Cosmetic, but useful. << * ERRF + DISKIO,12 35. Display directory information about specified file (possibly with wildcard notation). >> Needed for DIR subcommand. Cosmetic, but very useful. << DISKIO,13 36. Delete a specified file. ERASF is a generic macro. >> Cosmetic, but useful, especially for REMOTE server functions. << * ERASF + DISKIO,14 37. Rename a specified file. >> Cosmetic, but useful, especially for REMOTE server functions. << DISKIO,15 38. Copy a specified file. >> Cosmetic, but useful, especially for REMOTE server functions. << DISKIO,16 39. Parse input string for a filespec under a variety of circumstances. The name must be converted to a uniform internal format suitable for Kermit I/O routines. a) Native file for input (possible wild-card notation). b) Native file for output. c) Foreign filespec. d) TAKE file (input or output). e) Native file for utility operations. >> Essential. << FSPEC (q.v.) 40. Check a given filespec for uniqueness and either generate a unique new name if possible or return an error indication if necessary. Possibly query the user for permission to overwrite a file that already exists, provided the filespec was entered by hand. >> Essential. << FSPEC (q.v.) 41. Convert an internal filespec to the form for transmission. >> Essential. << FSPEC (q.v.) 42. Convert an internal filespec to the display form. >> Needed for STATUS display and transaction log. << FSPEC (q.v.) 43. Open a library *per se* for purposes other than transferring its members. OPENF is a generic macro. >> Useful if the concept of libraries is important. << * OPENF L + DISKIO,22 44. Skip over the first "n" records of a newly-opened input file. POINTF is a generic macro. >> Useful for SEND with line range. << * POINTF + DISKIO,23 COMMUNICATION FUNCTIONS 45. Open a specified communication line for I/O (default to the terminal connection). Set parameters needed for transparent operation. The procedure may depend on the type of terminal (or line) controller and should include both linemode and fullscreen types. After the line is open, if it is the terminal, no display messages will be issued by Kermit, and messages from other sources should also be suppressed, if possible. These opening functions are to be divided into controller-specific (of which there may be different variants) and general. >> Essential. << TERMIO/SCRNIO,1 + SETMSG,2 46. Close the current communication line. Restore normal operation. The same division of functions obtains as in #45. >> Essential. << TERMIO/SCRNIO,2 + SETMSG,3 47. Write a packet to the communication line. If possible, control the entire contents, including terminators. Also, if possible and if Kermit will immediately be requesting a read, begin the following read operation so that there is no delay between the completion of the write and the readiness of the system to read -- this may be important in a heavily loaded time-sharing environment. >> Essential. << TERMIO/SCRNIO,4 48. Read a packet from the communication line. If possible, suppress any prompts the system might normally supply. If possible, arrange for a timer interrupt after a specified wait such that the I/O request can be cancelled. >> Essential. << TERMIO/SCRNIO,5 49. For fullscreen lines, write a message to the screen despite the line having been opened. >> Cosmetic, but useful. << SCRNIO,6 *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* B. Hints. In general, the operation of porting Kermit-370 entails starting from one or more existing versions of the system-specific code (IKxMAC.ASM and IKxUTL.ASM) and replacing one set of system-specific code with another. Each subroutine has comments documenting the interface with the rest of the program, and a fair amount of the code itself deals with such bookkeeping details and can be carried over. Similarly, each macro begins with a brief function/syntax description. In one example (porting Kermit-370 to the MUSIC O.S.), about 2/3 of the final macro definition code had been carried across from CMS as well as about 2/5 of the final MUSIC-specific subroutine code. In all, only about 850 lines of non-comment code had to be written. In another example (porting to CICS), only about 1/2 of the macro definition code had been carried across, along with about 1/4 of the subroutine code. In some cases, particularly when the operating system is supplied in source form, it may be useful to examine the system code and macro definitions for helpful hints on the techniques of invoking system functions, manipulating filespecs, and the like. Care should be taken, of course, not to violate copyright restrictions. ------------------------------------------------------------------------ Parameters. It is necessary to define the symbols in the SSYMS macro. A useful technique is to compare two existing variants to determine which symbols are always present. Items in the KSYSTF macro are also system- specific, and many of them are required in all variants; some are not required, but are generally useful (again, compare existing variants for tips). ------------------------------------------------------------------------ Entry and exit conditions. Kermit at entry should have R13 -> 72-byte save area and R15 -> Kermit, and there must be a macro SAVE similar to that of MVS. If there is no system macro SAVE, Kermit must supply one itself. If necessary, that macro can distinguish between internal linkages (in which R13, R14, and R15 *must* follow type-I conventions) and the initial call from the system (which may be anything at all). The entry conditions for Kermit consist of two macro calls: SAVE (14,12),,&LABEL KMAIN ENTER plus code appropriate to internal linkages. &LABEL will be either GUPI or KERMIT. For internal linkages, that parameter is always "*". After the invocation of KMAIN, R13 must point to the original save area, of which the first 12 bytes must be unused, and if the values originally in R0 and R1 were important, they must be saved in bytes 20-27. KMAIN ENTER must assign free storage and zero-fill it; point register KWRKBASE at the storage, register KSUBBASE at Kermit, and R10 at COMMON; and set up pointers to the stack. KMAIN RETURN must release the storage, restore any registers necessary, and return to the system with the proper condition code (initially in R15). ------------------------------------------------------------------------ FSPEC. Notes from source code: * Entry: R1->name field, R0=flags selecting operation (see below) * For parse operations, SCANPTR defines the input string. * For getting foreign or display filespec, R7->output buffer * Exit: if not FFNEW, then R15=0 if ok, 1 if ?, 2 if bad. * For R15=1 or 2 R3,R4 give message. ERRNUM may be leftover. * * Flags: Notes: * Tasks: FFRCF FFSND FFGET FFNEW * Parse RECV X set ROVR properly * Parse SEND 1st X * Parse SEND 2nd X X * Parse GET 1st X * Parse GET 2nd X X set ROVR properly * Parse F-packet (FFHDR) X X X * Parse for Generic(FFUTL) X X FFWLD: allow partial * Parse TAKE * * Get unique name X R15: 0=>ok, 1=>bad * Interactive name check X X R15: 0=>ok, 1=>bad * Get foreign name (FFENC) X X R15->end of string * Get display form (FFDSP) X X R15->end of string Further explanation of entry conditions - "name field" is a fixed-length string of length LFID to be filled with the internal representation of a file name. SCANPTR is a pair of pointers (LEN, ADR) of a character string to be parsed, typically a string typed by the user, possibly in lower case. Note: Kermit assumes that a file specification will fit into a string of no more than 256 bytes, i.e., LFID must be <257. FSPEC parses out one filename at a time. There is, of course, the alternate command syntax for SEND that allows the user to specify a list of files. The only contribution of FSPEC to the parsing is to note the delimiter it finds after the name; the list control is managed by the generic code. SEND takes one or two parameters, namely, the native filename and, optionally, a different filename to send to the other Kermit. A reversed pair of parameters is taken for the GET subcommand: a required "foreign" filename and an optional overriding "native" one. Foreign filenames, since they depend on the system of the other Kermit, might be thought of as independent of the IBM/370 operating system, but Kermit-CMS offers a special syntax extension that isn't implemented in Kermit-TSO. Anyway, that is the meaning of SEND 1st, etc. The foreign filename, by the way, is stored in JFSPEC, which is a varying-length string in COMMON (one-byte length indicator, followed by a maximum of 47 bytes). "Parse RECV", in case that's not clear, means grab the filename, if any, entered on the RECEIVE subcommand, and (as the Note says), set flag ROVR in FL1, if a filename is actually found. I also note that the code clears flag NMOK in FL4 (in the CMS version), but that happens to be part of the internal logic of FSPEC to avoid duplicate efforts in filename collision testing. "Parse F-packet" means grab a (valid) filename from the file header sent from the other Kermit. "Parse for Generic" means grab a filename from the text string sent by the other Kermit for one of the Generic Server mode commands. The corresponding Note says that FFWLD set in the input flags means that part or all of the filename can be omitted to indicate all matching files, as in the DIRECTORY command. "Parse TAKE" means grab a file name from the text of a TAKE subcommand. The difference between "Get unique name" and "Interactive name check" is that the latter is permitted to type out a message and query the user for further instructions if necessary (as might be the case when the user types RECEIVE DUP.FILE), while the former must either find a unique name, or return an error condition. "Get foreign name" means putting the foreign filespec into a buffer (in ASCII) with JFSPEC taking precedence over whatever is found at (R1). Finally, "Get display form" is just the reverse of the various parse operations: the internal representation is converted to conventional external representation (with excess blanks, if any, removed according to whatever convention holds). ------------------------------------------------------------------------ FDB. File Descriptor Block + File Access Block: In IKxMAC.ASM, the FDBD macro has two parts, an FAB and FDB. The FAB is intended to map the operating system's macro, whereas the FDB is Kermit's local variables. Some of the variables in the FDB are used throughout the generic Kermit code. The common part begins at FDBD and includes everything mapped by FDBPAT macro, and also includes FABLRTR, which is a recent addition giving the maximum record length for output to a file (which may in CMS, for example, differ from the current largest record length). ------------------------------------------------------------------------ Host command execution. Not all operating systems make it possible for one application program (such as Kermit) to invoke another. When that is not possible, Kermit should make an effort to emulate the basic file-management commands corresponding to DISKIO functions 13-16 plus the appropriate commands (even if the system doesn't have them) to invoke on-line help and to display a file at the terminal. For an example of how such emulation can be done, see function 3 of SUPFNC in the MUSIC version of Kermit. Some calls to SUPFNC are generated internally by Kermit-370 itself (these are identified by *not* having flag UCMD set in FL4). Such calls should not require any syntax checking and may, in fact, be already converted to a special "system" format, if any, suitable for passing directly to the command processor. The details of formatting and syntax check will, of course, be highly system-specific. ------------------------------------------------------------------------ SCRNIO. Fullscreen packet I/O. See part C for calling sequence info. For the Series/1 interface (and whenever else possible), Kermit-370 takes advantage of a Read chained to a Write to speed up the I/O. Actually, the operation is chained by the Series/1, so Kermit issues both a write and a read synchronized by a hardware interrupt from the Series/1. Fullscreen buffer limits are defined by symbols MAXWS and MAXRS set in macro SSYMS. In principle, all you need to know is the sequence of calls to SCRNIO. You can handle the system interface in any convenient manner. The sequence is (by R0 code): 1, 6 (with greetings message), 4, 5, 4, 5, ... 4, 5, 2. The value of WRRD determines whether a "4" means Write/Read (value is 5) or just Write (value is 0) -- that value will always be 5 except possibly the last time. Even if WRRD is 0 on the last call with R0=4, there will still be a call with R0=5 just afterwards, followed by a call to release control of the screen. The difference between "4" and "6" is just that no read is required following a "6". Also, "6" is intended for displaying messages to the user, in case he's watching, but "4" is for sending to the micro Kermit. ------------------------------------------------------------------------ TERMIO. Similar to SCRNIO in many respects. TTY buffer limits are defined by symbols MAXWT and MAXRT set in the macro SSYMS. The way to signal a timeout from TERMIO is to return a packet of exactly one character: an ASCII 'T'. You can see an example by looking at the TSO version. There is a potential problem for Kermit transfers that arises if the user has a printable character for any editing functions used in the interpretation by the system of terminal input. Examples of such functions include character-delete and line-end (both normally found only on line-mode terminals). If such a character appears in a packet sent to the 370, the packet will be mangled unless Kermit takes special precautions. CMS Kermit deals with the problem by noting the LINEDIT setting when it starts up, turning off LINEDIT during a protocol transfer, and restoring LINEDIT afterwards. TSO Kermit, on the other hand, simply suppresses the user's line and character deletes during a transfer (and simultaneously saves the current values) and then restores them afterwards. The functions of saving, changing, and restoring the edit characters would be performed under variants 1, 2, and 3, respectively, of SETMSG. ------------------------------------------------------------------------ Type-out interception. Intercepting host command output depends on the operating system facilities. In any case, the info would go directly to the screen unless you first call SUPFNC,1 to start typeout interception. For example, under CMS that means intercepting all SVC's (and BALR's to the system typeout entry point) and copying the corresponding info into a buffer as it's generated (leaving x'15' separators). That sort of operation is self-pacing, so that the cleanup consists of nothing more than copying the end-of-buffer pointer into a global variable. Under TSO, the setup call creates a STACK entry such that the TSO-type utilities will write to a pre-allocated dataset. Cleanup in that case consists of closing the file and then reading the file into the buffer, again with X'15' (Newline) characters separating lines, and finally copying out the end-of-buffer pointer. If there's no general way to save the output of a class of utility programs, then you would just have to do what you can: put any preliminaries in SUPFNC,1 and the nitty-gritty (for, say, DIR) in DISKIO,13 with the buffer-read-back in SUPFNC,2/SUPFNC,5. You might want to get a copy of TSO Kermit to see how it does things. The expansion for WTEXT in the TSO version generates a call to a subroutine in COMMON which checks the interception flags and then either issues a TPUT or copies the info into the output buffer. ------------------------------------------------------------------------ GUPI. Updates for Kermit-370 are in the same format as in CMS, except that the multi-level updates are applied from a single, concatenated file, rather than a flock of separate updates listed by an AUX. You should take a look at implementing the generic update program GUPI for your operating system. Bear in mind that there are almost always some updates to the base generic source, so the "package" for installation must include a means of applying those, and it would also be nice if subsequent changes, particularly generic changes, could be transmitted to all systems in the same form. In any case, instructions for applying updates should be included in the IKxKER.BWR file (see IKCKER.BWR for a pattern). It is pretty easy to make a GUPI, once you've got Kermit: just take subroutine DISKIO (functions 1, 2, 3, 4, 9, and 10) plus any associated data structures and tack on a command interface. GUPI uses the same macros as Kermit. You can see a working example by getting IKTGUP.ASM + IK0GUP.ASM from Columbia. The only complication is that you'll need to make a macro library consisting of the macros in IK0MAC.ASM, IKxMAC.ASM, and IKxGUP.ASM. The awkward (but workable) alternative would be to convert all the COPY blocks in GUPI into macros as the MUSIC version does. Making a macro libary is simplified by the structure of the code: a) All the pieces have *COPY cards imbedded appropriately (the source components have each macro preceded by a card of the form *COPY macro-name to improve legibility). b) The builder may concatenate all the pieces in any order, both for Kermit itself and GUPI, then change the *COPY cards into the appropriate member-separators, and finally run the result through a PDS (library) generator. c) The "real" source for Kermit or GUPI can then be a small skeleton which consists of comments and COPY instructions (which refer to members of the macro+source library). ------------------------------------------------------------------------ Reentrancy. Kermit-370 is fully re-entrant in the generic sections, and provides a simple means for any system-specific code to be re-entrant as well. The ENTER, LOCALS, and EXIT macros can (and should) be used to begin a new routine, end the static code, and end the routine, respectively. Storage locations defined between the LOCALS and EXIT macros are allocated as temporary variables and initialized to zeroes for each invocation of the subroutine (and may be allocated recursively, if necessary). Sufficient stack space must be reserved for Kermit by setting the symbol STKDWDS in the SSYMS macro. The requirement is 18 doublewords per subroutine call plus the sum of all temporaries (rounded up to doublewords) for the subroutines in the longest path. There is automatic overflow checking at each subroutine call performed by COMMON code routine named SUBENT. The result of overflow is an immediate return with an error code from the subroutine, but that may still lead to unpredictable consequences, and STKDWDS should be given generous proportions. When TEST is set on in Kermit-370, the STATUS subcommand displays the maximum extent of stack space used (in doublewords). ------------------------------------------------------------------------ Miscellaneous notes. 1. Does your O.S. have a LINEND character facility like VM? If not, it might pay to copy the implementation of that from TSO Kermit. This will, of course, mean some changes to IKxMAC. 2. Would TAKE files generated by Kermit users tend to have line numbers imbedded? If so, it would pay to copy/adapt the stripping facility of TSO or CMS Kermit. 3. Does your O.S. have a way of timing out on a line-mode terminal read? The way to signal a timeout from TERMIO is to return a packet of exactly one character: an ASCII 'T'. You can see an example by looking at the TSO variant. *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* C. Module summary This summary was produced for Kermit-CMS 4.2.2. The system-specific modules vary (of course), but all should be quite similar to the CMS variant. Some of the differences lie in whether a particular entry point is treated as a separate routine or not. ALPHABETIC LIST OF SUBROUTINES Each item begins with a one-line description, possibly followed by more details, including entry and exit conditions and function. If any alternate entry points exist, each one is similarly described. Finally, all common references, callers, and calls are lists -- these are joint lists in the cases of routines with alternate entries. ACCTNG: save statistics for a transfer in the transaction log ENTRY ACCTST * add a new entry (name only) to the transaction log CALLERS- RECEIV SEND COMMON: Kermit-370 common routines/data areas CALLS- CWDSET DECODE DISKIO DUMP ENCODE FSPEC INTINI RIO RPACK RPAR SET SPACK SPAR STATUS SUPFNC CRCCLC: calculates crc * Calculate the CRC and return it in R15. Expects R5 to point to the * start of the data on which the CRC is calculated, and R6 to the * char after the last one. CALLERS- RPACK SPACK CWDSET (system-specific): set working directory * Set new 'working directory', i.e., filemode letter * Entry: SCANPTR string has option * Exit: R15=0 if ok, R15=1 if error or help needed. ERRNUM unchanged. ENTRY DSPACE * Show space in 'working directory' or other minidisk * Entry: SCANPTR string has option (none => working directory) * Exit: R15=0 if ok, R15=1 if error or help needed. ERRNUM unchanged COMMONS- COMMON CALLERS- COMMON SERVER SET CALLS- DISKIO DECODE: decode pkts from RDATA to WBUF * Exit: ERRNUM left unchanged unless there is an error. CALLERS- COMMON GENCMD RECEIV CALLS- OUTBUF DISKIO (system-specific): performs disk I/O functions * ERRNUM unchanged unless there is a disk error. * Function selected on entry by R0: * 0=> unnum: R1->FAB. Return R1->buffer,R0=# and remove the sequence * number (if any) from the buffer (used for TAKE files) * 1=> open (in): R1->pattern FDB, R2->name. Returns R0->FAB, R1->FDB * 2=> open (out): (same) * 3=> test name: R2->name. Returns R1->FDB if found (else R15=1) * 4=> close file: R1->adr(FAB). * 5=> set up search: R1->pattern name. * 6=> return next file in list: Returns R1->FDB + sets up FILNAM * 7=> close search (if any). * 8=> test CWD string: R1->string. Returns R15=0 if ok, else =1. * 9=> read: R1->FAB. Returns R15=12 if EOF, 0 if ok; R0=# data * 10=> write: R1->FAB. Returns R15=13 if disk full, 0 if ok. * 11=> test space: R1->pattern FDB (has size in Kbytes), * R2->name (used if FAB not found), R6->adr(FAB). Return R15=0 if ok. * 12=> analyze R/W error, set ERRNUM, make EMSG: R1->FAB, TMPDW=code * always returns R15=1 * 13=> directory info on file: R1->name. Returns R15=0 if ok. * 14=> delete file: R1->name. Returns R15=0 if ok. * 15=> rename file: R1->name, R2->new name. Returns R15=0 if ok. * 16=> copy file: R1->name, R2->new name. Returns R15=0 if ok. * 21=> save file status in directory: R1->FAB. (not used) * 22=> open library (in): R2->DDNAME. Return R15=0 if ok. * 23=> point for next read, R1->adr(FDB), R2=records to skip. * Return R15=0 if ok. CALLERS- COMMON CWDSET DUMP FSPEC GENCMD INBUF KERMIT OUTBUF RECEIV RIO SEND SERVER SET USNTRF CALLS- SUPFNC DUMP: show translation table or transaction log * Display current contents of table or log * Entry: SCANPTR string has option * Exit: R15=0 if ok, R15=1 if error or help needed. ERRNUM unchanged. ENTRY DUMPTOD * Extra entry point for dumping TOD (in sec) from R0 into buf * at R1 and return updated buffer ptr in R15 ENTRY GIVTAB * Save current translation table in STORAG into a TAKE file on disk * Entry: SCANPTR string has option * Exit: R15=0 if ok, R15=1 if error or help needed. ERRNUM set * appropriately as long as command syntax is ok, else unchanged. COMMONS- ERRTAB CALLERS- COMMON SCRNIO CALLS- DISKIO FSPEC STATUS TBLSET ENCODE: encode from RBUF into SDATA buffer CALLERS- COMMON SEND CALLS- INBUF ERPACK: send error packet based on ERRNUM COMMONS- ERRTAB CALLERS- GENCMD RECEIV SEND SERVER CALLS- SPACK STATUS FOPSTR: test string for file options * Entry: R1->Address of option field, R6->string, R7=length - 1 * Exit: R15=0 + R6,R7 fixed if ok, R15=1 if error (msg ptrs set up) CALLERS- FSPEC FSPEC (system-specific): extract filespec from scan string * Entry: R1->name field, R0=flags selecting operation (see below) * For parse operations, SCANPTR defines the input string. * For getting foreign or display filespec, R7->output buffer * Exit: if not FFNEW, then R15=0 if ok, 1 if ?, 2 if bad. * For R15=1 or 2 R3,R4 give message. ERRNUM may be leftover. * See part B for calling flags. CALLERS- COMMON DUMP GENCMD RECEIV SERVER SET USNTRF CALLS- DISKIO FOPSTR GENCMD: send a Generic command * Entry: SCANPTR has string * Exit: R15=0 if ok, 1 if help needed, 2 if bad parameter * ERRNUM set appropriately CALLERS- USNTRF CALLS- DECODE DISKIO ERPACK FSPEC INTINI OUTBUF RECEIV SEND INBUF: read next disk record into RBUF * Exit: R15=0 if ok, -1 if EOF, 1 if read error (ERRNUM set) CALLERS- ENCODE NPREAD CALLS- DISKIO INTINI: Initialize/reset terminal for protocol * If R1 is 0, reset for interactive unless in Server mode. * If R1 is positive, set up for protocol: * 1 for SERVER, 2 for SEND, 3 for RECEIVE, 4 for short msg * R15 = 0 on return if ok CALLERS- COMMON GENCMD SEND SERVER USNTRF CALLS- SCRNIO SUPFNC TERMIO KERMIT: main entry point * Assign buffers, initialize STORAG section; do Kermit; return. COMMONS- COMMON KSYSNIT CALLS- DISKIO SCRNIO SPAR TBLSET USNTRF KHDMP: dump storage to log file (not generated unless &KTRACE is YES) * Dump area to log * Entry: R1->area, R0=length, R2-> 8-byte title for area * Exit: R15=0 if ok KHELP (system-specific): perform HELP command * Handle HELP command, rest of string given by SCANPTR. COMMONS- SETCMDS CALLERS- USNTRF CALLS- SUPFNC NPREAD: copy from RBUF to SDATA buffer (no encoding) CALLERS- SEND CALLS- INBUF OPTPKT: compute optimum packet size * Entry: TINSV contains stack of data * Exit: R15=0 if no limit, else optimum packet size (per algorithm) CALLERS- SEND STATUS OUTBUF: write record from WBUF to a disk file * Entry: R1=length of buffer (which starts where WBUF points) * Exit: R15=0 if ok, other if error (ERRNUM set) CALLERS- DECODE GENCMD RECEIV CALLS- DISKIO RECEIV: receives a file * Receive file(s) and set ERRNUM appropriately * Entry: filespec in FILNAM if ROVR is set, latest received packet in buffer COMMONS- COMMON CALLERS- GENCMD SERVER USNTRF CALLS- ACCTNG DECODE DISKIO ERPACK FSPEC OUTBUF RPACK RPAR SPAR SUPFNC TBLSET RIO: Read packet into receive packet buffer ENTRY SIO * Send packet in SNDPKT CALLERS- COMMON RPACK SEND SPACK CALLS- DISKIO SCRNIO TERMIO RPACK: Read and validate a packet * ERRNUM set if error found, unchanged otherwise CALLERS- COMMON RECEIV CALLS- CRCCLC RIO RPAR: sets up parms to send to other host ENTRY RPARSET * set up for exchange (RPAR to be called 1st) CALLERS- COMMON RECEIV SEND SERVER CALLS- SCRNIO TERMIO SCRNIO (system-specific): Handle screen I/O via protocol converter * R1 points to a pair of (adr,len) for read or write. If I/O is * successfull, R15 returns transferred byte count (else returns -1). * Command code is in R0: * 0 => Clear screen on console (not comm line) * 1 => Open screen for I/O 4 => Write packet * 2 => Close screen 5 => Read packet * 3 => Reset screen status after 6 => Write message (no ATTN) * environment changes 7 => Read screen buffer ENTRY SETMSG * Entry: R1 selects operation * Exit: R15=0 if ok * 1-> Analyze user environment, determine if suitable. * Save quantities needed and condition line for entering commands. * Perform any system-dependent initialization. * 2-> Condition line for protocol transfers. * 3-> Decondition line at end of transfer. * 4-> System-dependent clean-up at exit. * 5-> Reperform system-dependent initialization after SET LINE. COMMONS- KSYSNIT CALLERS- INTINI KERMIT RIO RPAR SET SUPFNC CALLS- DUMP USNTRF SEND: sends a file * Send file(s) and set ERRNUM appropriately * Entry: filespec pattern in IFILE, Disp code (if any) in R1 CALLERS- GENCMD SERVER USNTRF CALLS- ACCTNG DISKIO ENCODE ERPACK INTINI NPREAD OPTPKT RIO RPAR SPAR SUPFNC SERVER: performs Server mode functions * Exit: ERRNUM set appropriately. CALLERS- USNTRF CALLS- CWDSET DISKIO ERPACK FSPEC INTINI RECEIV RPAR SEND SPAR SUPFNC USNTRF SET: perform SET command options * Set/change values in STORAG. * Entry: SCANPTR string has option * Exit: R15=0 if ok, 1 if help needed, 2 if bad parameter name * ERRNUM unchanged ENTRY SHOW * Display current values in STORAG. * Entry: SCANPTR string has option * Exit: R15=0 if ok, 1 if help needed, 2 if bad parameter name * ERRNUM unchanged COMMONS- SETCMDS ETCETERA CALLERS- COMMON CALLS- CWDSET DISKIO FSPEC SCRNIO SETCMDS SUPFNC TBLSET SPACK: fill sending packet buffer and send it CALLERS- COMMON ERPACK USNTRF CALLS- CRCCLC RIO SPAR: use parms from other host in RDATA ENTRY SPARSET * set up for exchange (SPAR to be called 1st) CALLERS- COMMON KERMIT RECEIV SEND SERVER STATUS: display latest error (if any), transfer statistics, etc. * Exit: R15=0. ERRNUM unchanged. ENTRY PEMSG * Display just error message and its backup explanations. COMMONS- ERRTAB CALLERS- COMMON DUMP ERPACK USNTRF CALLS- OPTPKT SUPFNC (system-specific): various supervisor functions * On entry, R1 = operation code, R0 = possible ptr * Exit: R15 set (0 => ok, <0 => illegal cmd, >0 => depends) * ERRNUM set appropriately (R1=1,3,4) or unchanged (2,5-11) * 1 -> Start typeout interception. N.B. &MAXLR >> 2048 for this * 2 -> Clean up afterwards and stop interception * 3 -> Execute host command with or without interception * If UCMD set, SCANPTR gives text, else R0->text,R6=len * 4 -> Execute CP command with or without interception * R0->text, R6=len * 5 -> Stop interception if going * 6 -> Retrieve original cmd parm string into CBUF (R15=1 if null) * 7 -> Test for stacked lines, return number in R15 * 8 -> Log off (doesn't return!) * 9 -> Wait specified time * 10-> Return clock time in R15 (centisec) * 11-> Setup up new prompt string at (R0) CALLERS- COMMON DISKIO INTINI KHELP RECEIV SEND SERVER SET USNTRF CALLS- SCRNIO TBLSET: set up character set * Define new translation tables * Entry: Names of table in TRNALF and FILALF, R1->tables * R0->item just changed, if any (else, 0) * Tables should be a pair with ATOE first * Exit: R15=0 if ok, R15=1 if error ERRNUM unchanged. ENTRY TBLATT * Entry: R6->Designator string, R7=length * Exit: Correct table set up and R15=0 if ok, else 1 COMMONS- COMMON TRNTBLD CALLERS- DUMP KERMIT RECEIV SET TERMIO (system-specific): Handle terminal I/O * R1 points to a pair of (adr,len) for read or write. If I/O is * successfull, R15 returns transferred byte count (else returns -1). * Command code is in R0: * 1 => Open line for I/O 4 => Write packet * 2 => Close line 5 => Read packet * 3 => Reset line status after ( 6 => Write message ) not used * environment changes ( 7 => Read buffer ) not used COMMONS- COMMON CALLERS- INTINI RIO RPAR USNTRF: execute main loop * Execute Kermit commands (beginning with default TAKE files) * Entry: environment already set up * Exit: R15=0, ERRNUM set appropriately COMMONS- COMMON CALLERS- KERMIT KHELP SCRNIO SERVER CALLS- DISKIO FSPEC GENCMD INTINI KHELP RECEIV SEND SERVER SPACK STATUS SUPFNC - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ALPHABETIC LIST OF COMMON BLOCKS COMMON: Kermit-370 common data areas USED BY- CWDSET KERMIT KSYSNIT RECEIV TBLSET TERMIO USNTRF ERRMSGS: text of error messages USED BY- ERRTAB ERRTAB: List of error messages COMMONS- ERRMSGS USED BY- DUMP ERPACK STATUS ETCETERA: overflow from COMMON USED BY- SET KSYSNIT: initial parameter values USED BY- KERMIT SCRNIO SETCMDS: tables of command keywords USED BY- KHELP SET TRNTBLD: translation tables and variations thereon USED BY- TBLSET